Overview

Extend the TypedRest documentation with additional pages covering link handling features and serializers. The documentation should cover multiple language implementations (.NET and TypeScript) using the existing tabbed code example format.

New Pages to Create

1. docs/link-handling/relative-uris.md

Document hard-coded relative URIs between endpoints, including:

• Basic usage of relative URIs
• The non-standard ./ prefix pattern for appending trailing slashes to parent URIs before resolving relative URIs
• Examples showing the difference between "subresource" and "./subresource"
• When to use the ./ prefix
• Default links via SetDefaultLink

2. docs/link-handling/uri-templates.md

Document URI templates:

• Link to RFC 6570 for template syntax details (don't duplicate RFC content)
• Focus on how to use templates in TypedRest
• Server-provided templates via Link header and HAL
• Resolving templates with LinkTemplate() method
• Default link templates via SetDefaultLinkTemplate
• Built-in defaults in Collection/Indexer endpoints

3. docs/link-handling/link-header.md

Document links transmitted via HTTP Link Header:

• Link header format per RFC 8288
• Extracting links with GetLinks() and Link() methods
• The non-standard templated=true extension for URI templates in headers
• Supported link header attributes (rel, title, templated)

4. docs/link-handling/hal.md

Document links encoded in resources via HAL:

• Link to HAL specification (don't duplicate spec content)
• Focus on how to use HAL in TypedRest
• Content type application/hal+json
• Using HAL links with standard link resolution methods
• Multiple links and templated links in HAL
• Combining with header links via AggregateLinkExtractor

5. docs/link-handling/serializers.md

Document serializers with a table showing which formats are supported by which TypedRest version:

Format	.NET	TypeScript
JSON (Newtonsoft.Json)	✅ Default	❌
JSON (System.Text.Json)	✅ Separate NuGet	❌
JSON (Native)	❌	✅ Default
XML	✅	❌
BSON	✅	❌

Include:

• Configuration options for each serializer
• How to use System.Text.Json via TypedRest.SystemTextJson NuGet package
• Custom serializers in TypeScript
• Custom JSON media types (+json suffix handling)

Files to Update

docs/link-handling/index.md

Expand the current brief list into a proper overview with:

• Links to all new pages
• Brief description of link resolution methods (GetLinks, Link, LinkTemplate)
• Reference to serializers page

docs/link-handling/.pages

Create navigation file:

nav:
  - index.md
  - relative-uris.md
  - uri-templates.md
  - link-header.md
  - hal.md
  - serializers.md

docs/endpoints/index.md

Add a new section "Navigating Between Endpoints" at the end that:

• Explains the referrer parameter inherits configuration including serializers
• Lists the different ways to link endpoints (relative URIs, URI templates, Link headers, HAL)
• Links to the link-handling documentation

Code Examples

All code examples should use the existing tabbed format with both C# and TypeScript versions:

=== "C#"

    ```csharp
    // C# example
    ```

=== "TypeScript"

    ```typescript
    // TypeScript example
    ```

Reference Implementation Details

Relative URI ./ Pattern

From .NET UriExtensions.cs:

=> new(relativeUri.StartsWith("./") ? baseUri.EnsureTrailingSlash() : baseUri, relativeUri);

From TypeScript Endpoint.ts:

protected join(relativeUri: string): URL {
    return new URL(
        relativeUri,
        relativeUri.startsWith("./") ? Endpoint.ensureTrailingSlash(this.uri) : this.uri);
}

Link Template Support in Headers

The HeaderLinkExtractor in both implementations parses templated=true from Link headers - this is a non-standard extension.

HAL Link Extraction

Both implementations use HalLinkExtractor that looks for application/hal+json content type and parses _links objects.

Serializers

• .NET: NewtonsoftJsonSerializer (default), SystemTextJsonSerializer (separate package), XmlSerializer, BsonSerializer
• TypeScript: JsonSerializer (default, uses native JSON.parse/stringify)